To perform a mail merge with Impression an application must follow certain protocols defined by the Impulse message passing system. Impression can be commanded to do things by sending Impulse messages to it. A small application called Importer already uses this system to perform mail merges with Impression and it is written in BASIC as an example of how to use Impulse.
Impression supports the following Impulse commands...
Merge
Print
Edit
ClearMerge
These are all described in the standard form in Impressions !Help file.
The basic sequence of merging records from a database into an Impression document is as follows...
procedure mailmerge
begin
Get DocName;
Send "Edit Off";
Repeat
Get record ready;
Send "Merge";
{Respond to requests for data being sent from Impression}
Wait for reply to Merge;
Send "Print";
Wait for reply to Print;
Until all records are done;
end;
This example is simplified by the fact that the user is not given any chance to control the mail merge once it has started. If he were able to stop the process and examine a record the database would have to send "Edit Off" and "Edit On" commands to prevent the user from screwing up the document with merged data in it.
All of these commands have to be sent to a certain document in Impression - sending them to Impression alone is not good enough.
To start a merge operation into a document you must, therefore, first know its name. The only way to find this currently is to respond to the DataSave message sent by Impression when the user drags an Impression file icon onto your application. You can assume that the leafname (stripped of the initial pling character) is the name of the document that you should be talking to.
Strictly speaking, you should also attempt to find the name of the task that sent the DataSave message and not just assume that it was Impression but there is no way to do that at the moment.
Now that you have the destination name, you can send the Merge command to Impression. The Merge command must be sent using reason code Impulse_Request otherwise no reply will ever come back. The reply to this command will not be sent until all the merge commands in the document have been sent as Impulse commands and all have been replied to in some way. So your program must be prepared to respond to all normal Wimp events including requests for data from the database until the reply to the merge command is received. While !Importer is waiting for the reply to the Merge command it prevents the user from upsetting it with click events by greying the buttons.
When the reply has been received you can send the Print command. Once again, the print command will not reply immediately and your program must respond to other Wimp events before the reply is returned.
So far, I have described how a database program drives the mail merge facilities in Impression, but that is not all a database must do. It must also provide methods which can be embedded in the Impression document to fetch the mail merge data. !Importer supplies two, very simple, methods - GetField and GetDateTime. GetField returns a single field from a record and GetDateTime returns a formatted date string. The methods supplied by real databases will probably be much more flexible than these but the principle of operation is the same.
When the database has received a request for data it should not return the data in the reply to the request but in a following data transmission. In practice this means that you reply by calling Impulse_SendMessage with r0=Impulse_Reply and r7 set to the size of the data which will follow the reply. Impulse will then start generating Impulse_SendData events which your program should respond to by calling Impulse_TransmitData until the all the data has been transferred.
